Now that you understand partition and row keys, there is one
final query variant to consider. In several scenarios, Azure tables will
return a subset of the entities that matched the query. This could
happen if the number of entities matching the query exceeds 1,000, if it
exceeds a query timeout set (by default) to 60 seconds, if it exceeds 4
MB combined, or for a few other reasons. You can also force Azure tables
to return only a subset by asking for only a specific number of entities
at a time.
In all of these cases, Azure tables will return two
continuation tokens: one for the next partition
and one for the next row. When you want to get the next set of results,
you send these continuation tokens back to the Azure Table service.
These tokens essentially tell the Table service where your query left
off, and which partition/row to continue with.
For example, if you queried a hypothetical Employee table for 5 employees at a time (assuming the employees
are partitioned by department), you would see something such as the
following:
GET /EmployeeTable()?$top=5&NextPartitionKey=HR&NextRowKey=EmpID205
And as shown in the following code, you would get results that
have the x-ms-continuation-NextPartitionKey and
x-ms-continuation-NextRowKey headers,
the values of which are the continuation tokens:
HTTP/1.1 200 OK
Cache-Control: no-cache
Transfer-Encoding: chunked
Content-Type: application/atom+xml;charset=utf-8
Server: Table Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 91e00f79-7b87-4733-ab71-aa7b71a06c58
x-ms-continuation-NextPartitionKey: Engineering
x-ms-continuation-NextRowKey: EmpID1000
When writing .NET code against tables, you don’t need to deal with
continuation tokens if you don’t want to. If you enumerate through all
the results of a query, the storage client library does the right magic
under the covers to get and insert continuation tokens. Look for the
AsTableServiceQuery
extension method which deals with continuation tokens automatically for
you.
However, sometimes you must do this manually. The canonical
scenario is when you want page output—such as several pages in a blog,
and you want “back” and “next” links. Example 1 shows code to retrieve
continuation tokens. A new class, DataServiceQuery, is used here, since it gives
you access to the headers of the queries you are performing.
Example 1. Retrieving continuation tokens
// Code to get continuation tokens from executing a query //'query' below refers to a typical query created using CreateQuery var dsQuery = (DataServiceQuery<Contact>)query; var res = dsQuery.Execute();
var qor = (QueryOperationResponse)res; string partitionToken = null; string rowToken = null; qor.Headers.TryGetValue("x-ms-continuation-NextPartitionKey", out partitionToken); qor.Headers.TryGetValue("x-ms-continuation-NextRowKey", out rowToken);
|
Once you have the continuation tokens, you must insert them into
the subsequent query. Again, you use the DataServiceQuery class to do this, as shown in
Example 2.
Example 2. Inserting continuation tokens
//Code below shows how to insert continuation tokens into a query var dsQuery = (DataServiceQuery<Contact>)query; query = query .AddQueryOption("NextPartitionKey", partitionToken) .AddQueryOption("NextRowKey", rowToken);
|
Note:
This code assumes there will always be a continuation token for
partitions and rows. In some cases, you might get just one (if you’re
on the last row or the last partition). In production code, you must
add checks for that.